WebForm.callUrl

Calls the specified URL and displays any resulting HTML page to the user. Use this method to call a URL based application that will subsequently return to Ebase e.g. a payment gateway.

This method can only be called within the context of a web form event. When called from any other context, e.g. a JSP, a RuntimeException is thrown.

The called application can set any Ebase form field values on return by adding them to the return URL. Form field names can be specified in either upper case or lower case.

Execution of the current script is suspended and resumes with the next statement when the called application returns. The current transaction is committed prior to calling the application, and a new transaction is started when the called application returns.

Http protocol of either GET or POST can be specified, where GET is the default.
Note: when POST is specified, the system writes an additional HTML page to the browser to invoke the specified URL. This page is added to the browser's history cache and interferes with the operation of the browser back button. The result is that the user will not be able to use the back button to navigate back from the called URL to the Ebase form. For this reason, it is recommended that POST is only used when there is no alternative, or for forms which do not support the back button.

In order to return to Ebase, the called application must be supplied with a return URL. This return URL should invoke the ufsreturn servlet and include the Ebase form session id parameter ebz i.e. the URL should be of the type domain/ufs/ufsreturn?ebz=xxxx e.g. http://mydomain/ufs/ufsreturn?ebz=1_1283432908172. The full return URL is available via method #getReturnUrl() and can be passed to the called application if required as shown in the example below. As default, the return URL is added automatically by the system as parameter ufsReturnURL.

Not all servers support the ufsReturnURL parameter. The ufsReturnURL parameter can be excluded from the URL parameters by adding addUfsReturnURL=false to the parameter Map (example 3 below)

The return call can be made using either Http protocol GET or POST. Care should be taken to ensure that the domain name (or host name or ip address) used on the return URL is the same as the one used to initially invoke the Ebase form. If these domain names are different, an error page will be displayed with the message:

The request has timed out - please try again

On return, the ebz parameter is used to load the appropriate form context and execution of the form is resumed from the point where the callUrl() method was executed. If the ebz parameter is not supplied on the return URL, the most recent form context will be used.

It is best practice to pass any parameters to a called application via the parameters Map (example 1 below). However, if parameters are added to the URL directly, these should be encoded (example 2 below). Parameters passed via the parameters Map should not be encoded as this is done automatically by the system.

Javascript example 1 (using parameters Map):

 var parms = {};
 parms.cardid = fields.CREDIT_CARD_NO.displayValue;
 parms.amount = fields.PAYMENT_AMOUNT.displayValue;
 parms.returl = form.getReturnUrl();
 form.callUrl("http://www.xxxpaymentservice.com", parms, form.HTTP_PROTOCOL_GET);
 

Javascript example 2 (adding parameters directly to url):

 var encoder = java.net.URLEncoder;
 var encoding = "UTF-8";
 var parm1 = encoder.encode(fields.CREDIT_CARD_NO.displayValue, encoding);
 var parm2 = encoder.encode(fields.AMOUNT.displayValue, encoding);
 var returl = encoder.encode(form.getReturnUrl(), encoding);
 var url = "http://www.xxxmypaymentservice.com" 
  + "?cardid=" + parm1
  + "&amount=" + parm2
  + "&returl=" + returl; 
 form.callUrl(url, null, form.HTTP_PROTOCOL_GET);
 

Javascript example 3 (do not add ufsReturnURL to the URL parameters):

 var parms = {};
 parms.cardid = fields.CREDIT_CARD_NO.displayValue;
 parms.amount = fields.PAYMENT_AMOUNT.displayValue;
 parms.returl = form.getReturnUrl();
 parms.addUfsReturnURL = false;
 
 var url = "http://www.xxxmypaymentservice.com"; 
 form.callUrl(url, parms, form.HTTP_PROTOCOL_GET);